/********************************************************************************
 * Project Name		[JavaEE_Components]
 * File Name     	[JavaMail02.java]
 * Creation Date 	[2015-01-01]
 * 
 * Copyright© ge.y.yang@gmail.com All Rights Reserved
 * 
 * Work hard, play harder, think big and keep fit
 ********************************************************************************/
package javamail._notes;

/**
 * 邮件发送API
 * 
 * @author 不落的太阳(Sean Yang aka ShortPeace)
 * @version 1.0
 * @since jdk 1.8
 * 
 */
public final class JavaMail02 {

	public void sendMailSteps() {
		/**
		 * JavaMail发送邮件的步骤<br/>
		 * 
		 * 1. 根据Propreties文件创建一个Session<br/>
		 * 2. 创建一个MimeMessage对象, 设置收件人, 发件人, 主题等信息<br/>
		 * 3. 创建一个或多个MimeMultipart和MimeBodyPart对象, 用于设置附件, 正文图片等信息<br/>
		 * 4. 使用Transport对象来发送邮件<br/>
		 */
	}

	public void session() {
		/**
		 * javax.mail.Session, Session对象用来充当连接工厂, 可以同时处理配置设置和身份验证<br/>
		 * 
		 * Session对象可以通过以下方式创建:<br/>
		 * 
		 * 1. 基于编程方法: 使用java.util.Properties对象来存储一些配置信息<br/>
		 * <code>
		 * public static Session getDefaultInstance(Properties props)
		 * public static Session getDefaultInstance(Properties props,Authenticator auth)
		 * public static Session getInstance(Properties props)
		 * public static Session getInstance(Properties props,Authenticator auth)
		 * </code><br/>
		 * <code>
		 * private static Properties properties = null;
		 * 
		 * static {
		 *     properties = new Properties();
		 *     properties.setProperty("mail.transport.protocol", MailConstants.PROTOCOL_SMTP);
		 *     properties.setProperty("mail.smtp.host", MailConstants.SMTP_HOST_OF_SINA);
		 *     properties.setProperty("mail.smtp.port", MailConstants.SMTP_PORT_OF_SINA);
		 *     properties.setProperty("mail.smtp.auth", String.valueOf(MailConstants.IS_AUTHORIZATION_NEED));
		 *     properties.setProperty("mail.debug", String.valueOf(MailConstants.IS_DEBUG_MOD_ENABLED));
		 * }
		 * 
		 * Session session = Session.getInstance(properties, new MailAuthenticator(emailSender, PasswordUtils.readPassword(emailSender)));
		 * </code><br/>
		 * 
		 * 2. 通过查找存储在JNDI服务的管理对象<br/>
		 * <code>
		 * InitialContext context = new InitialContext(); 
		 * Session session = (Session) context.lookup("usersMailSession");
		 * </code><br/>
		 * usersMailSession是用作javax.mail.Session对象的管理对象的JNDI名称的对象<br/>
		 * usersMailSession可以创建并配置必要的参数作为名称/值对, 包括邮件服务器, 主机名, 端口号等<br/>
		 * 
		 * 主要方法<br/>
		 * getInstance(Properties props);<br/>
		 * getInstance(Properties props, Authenticator auth);<br/>
		 * getDefaultInstance(Properties props);<br/>
		 * getDefaultInstance(Properties props, Authenticator auth);<br/>
		 * getTransport();<br/>
		 * getTransport(String protocol);<br/>
		 * getStrore();<br/>
		 * getStrore(String protocol);<br/>
		 * setDebug(true);输出调试信息<br/>
		 */
	}

	public void authenticator() {
		/**
		 * javax.mail.Authenticator, 代表可以提供用户认证信息的对象<br/>
		 * 
		 * Authenticator是一个抽象类, 可以创建一个子类javamail.utils.MailAuthenticator,
		 * 通过用户名和密码创建MailAuthenticator对象并结合javax.mail.Session的方法来创建认证的Session
		 * <br/>
		 * <code>
		 * Session session = Session.getDefaultInstance(props, auth);
		 * </code><br/>
		 * 
		 * javax.mail.PasswordAuthentication, 用于封装用户认证信息<br/>
		 * new PasswordAuthentication(String username, String password);<br/>
		 * getUserName();<br/>
		 * getPassword();<br/>
		 */
	}

	public void message() {
		/**
		 * javax.mail.Message, 一个Message实例代表了一封电子邮件<br/>
		 * 
		 * javax.mail.MimeMessage<br/>
		 * 
		 * 构造方法<br/>
		 * new MimeMessage(session);从Session中创建MimeMessage的实例 <br/>
		 * new MimeMessage(session, inputStream); 从eml文件输入流创建MimeMessage实例<br/>
		 * 
		 * 其他方法<br/>
		 * setSubject(String subject); 设置邮件主题<br/>
		 * setFrom(new InternetAddress("emailSender")); 设置邮件发送人<br/>
		 * setRecipients(RecipientType.TO, new Address[] {}); 设置收件人 <br/>
		 * setRecipients(RecipientType.TO, String emailRecipient); 设置收件人<br/>
		 * setRecipient(RecipientType.CC, new InternetAddress()); 设置抄送人<br/>
		 * setRecipient(RecipientType.BCC, new InternetAddress()); 设置密送人<br/>
		 * setHeader("X-Priority", "1"); 设置优先级<br/>
		 * setHeader("Disposition-Notification-To", emailSender); 设置回执<br/>
		 * setReplyTo(new Address[]{}); 设置回复人[收件人回复邮件时默认的对方收件人]<br/>
		 * setSentDate(new java.util.Date()); 设置发送时间<br/>
		 * setText(String text); 如果是纯文本内容, 使用该方法设置邮件内容<br/>
		 * setContent(Object content, String mimeType); 设置邮件内容<br/>
		 * setContent(Multipart mp); 设置邮件内容<br/>
		 * setFlag(Flags.Flag, boolean); 设置当前Message的邮件标记, true表示设置到当前Message对象,
		 * false表示从当前Message对象中清除标记<br/>
		 * saveChanges(); 保存邮件设置, 发送邮件之前调用此方法<br/>
		 * writeTo(OutputSteam out); 将邮件写出到本地, 生成eml文件<br/>
		 * 
		 * 上述的set方法都有对应的get方法, 可用于解析邮件<br/>
		 * 
		 * javax.mail.Message.RecipientType<br/>
		 * Message.RecipientType.TO; 收件人<br/>
		 * Message.RecipientType.CC; 抄送人<br/>
		 * Message.RecipientType.BCC; 密送人<br/>
		 */
	}

	public void mimeBodyPart() {
		/**
		 * javax.mail.MimeBodyPart, 表示邮件的一个MIME消息<br/>
		 * 
		 * 构造方法<br/>
		 * new MimeBodyPart();创建一个默认的MimeBodyPart对象<br/>
		 * new MimeBodyPart(InputStream in);使用输入流读取的数据创建一个MimeBodyPart对象<br/>
		 * 
		 * 其他方法<br/>
		 * setDataHandler(DataHandler handler); 设置一个读取资源的DataHandler<br/>
		 * setContentID(String cid); 用于设置头消息中的Content-ID字段<br/>
		 * setDisposition(String str); 用于设置头消息中的Content-Disposition字段<br/>
		 * setFileName(String attachedFileName); 用于设置邮件附件的名称,
		 * 即用于设置Content-Disposition字段中的filename属性<br/>
		 */
	}

	public void mimeMultipart() {
		/**
		 * javax.mail.MimeMultipart, 表示一个由多个MIME消息组成的混合MIME消息<br/>
		 * 
		 * 类型<br/>
		 * related: 表示邮件体中的内容是关联组合类型, 例如邮件正文使用Html代码内嵌图片, 其中的Html代码依赖于图片资源 <br/>
		 * mixed: 表示邮件体中的内容是混合组合类型, 代表整封邮件内容的MimeMultipart必须为mixed<br/>
		 * alternative: 表示邮件体的内容是选择组合类型, 例如邮件内容既使用Html, 又使用text文本,
		 * 则可以将他们嵌套在一个类型为alternative的MimeMultipart中<br/>
		 * 
		 * <code>
		 * ------------------------------multipart/mixed-------------------------------
		 * |																		  |
		 * |  ------------------------multipart/related-------------------- 		  |
		 * |  |														      |  ------   |
		 * |  |   ----------multipart/alternative--------	----------    |  |附件 |   |
		 * |  |	  |	    ------------	-----------		|	|内嵌资源 |    |  ------   |
		 * |  |	  |	    |纯文本文件|		|超文本正文|		|   ----------    |           |
		 * |  |	  |	    ------------	-----------		|   ----------    |  ------   |
		 * |  |	  |										|   |内嵌资源 |    |  |附件 |   |
		 * |  |	  ---------------------------------------	----------    |  ------   |
		 * |  |                                                           |           |
		 * |  -------------------------------------------------------------           |
		 * ----------------------------------------------------------------------------
		 * </code>
		 * 
		 * 如果整封邮件只有普通文本与Html文本, 则应该将multipart定义为alternative<br/>
		 * 如果整封邮件包含Html文本和内嵌资源[图片], 但没有附件, 则应该将multipart定义为related<br/>
		 * 
		 * MIME消息头字段<br/>
		 * content-type: 表示content的类型, 如image, text, multipart, message<br/>
		 * content-transfer-encoding: 表示MIME消息体中的内容采用的编码方式<br/>
		 * content-disposition: 有inline[直接处理]和attachment[当作附件处理]两种方式<br/>
		 * content-id: 用于为multipart/related组合消息中的内嵌资源指定唯一标识<br/>
		 * 
		 * 构造方法<br/>
		 * new MimeMultipart(); 使用mixed作为MIME类型构造MimeMultipart对象<br/>
		 * new MimeMultipart(String type); 使用指定的MIME类型构造MimeMultipart对象,
		 * type可取值为[mixed, related, alternative]<br/>
		 * 
		 * 其他方法<br/>
		 * addBodyPart(BodyPart part); 添加BodyPart对象到当前MimeMultipart对象中,
		 * 加在原有BodyPart列表的尾部<br/>
		 * addBodyPart(BodyPart part, int index);
		 * 添加BodyPart对象到当前的MimeMultipart中, index指定了插入到原有BodyPart列表的位置<br/>
		 * 
		 * setSubType(String type); 设置该MimeMultipart对象的MIME类型, type可取值为[mixed,
		 * related, alternative]<br/>
		 * 
		 * getContentType(); 返回该MimeMultipart对象的content-type属性值<br/>
		 * 
		 * getBodyPart(int index); 返回指定索引的BodyPart对象<br/>
		 * getBodyPart(String cid); 返回指定cid的BodyPart对象,
		 * cid是MimeBodyPart调用setContentID(cid)中的值<br/>
		 * 
		 * getCount(); 返回该MimeMultipart对象中保存的BodyPart数目
		 */
	}

	public void internetAddress() {
		/**
		 * javax.mail.Address<br/>
		 * 
		 * 常用子类<br/>
		 * javax.mail.internet.InternetAddress, 表示邮件地址<br/>
		 * 
		 * 构造方法<br/>
		 * new InternetAddress(String emailSender) <br/>
		 * new InternetAddress(String emailSender, "不落的太阳", "UTF-8")<br/>
		 * 
		 * 其他方法<br/>
		 * InternetAddress.parse(String address); 通过字符串构建InternetAddress<br/>
		 * <code>
		 * InternetAddress.parse("\"" + MimeUtility.encodeText("不落的太阳") + "\"<javamail_sns@sina.com>")
		 * </code><br/>
		 * getAddress(); 返回字符串形式的邮件地址<br/>
		 */
	}

	public void transport() {
		/**
		 * javax.mail.Transport, 抽象类, 邮件消息传送类, 其通常使用SMTP协议来发送消息<br/>
		 * 
		 * 主要方法<br/>
		 * connect();使用保存在Session中的属性连接邮件服务器,session必须使用认证的方式得到<br/>
		 * connect(String host, String username, String password);<br/>
		 * connect(String host, int port, String username, String password);
		 * sendMessage(Message message, Address[] addresses);
		 * 调用此方法之前必须要调用message.saveChanges()<br/>
		 * close(); 断开与服务器的连接<br/>
		 * Transport.send(Message message);会自动调用message.saveChanges()方法<br/>
		 * Transport.send(Message message, Address[] addresses);<br/>
		 * 
		 * <code>
		 * // 获得Transport实例
		 * Transport transport = session.getTransport("smtp");  
		 * // 打开连接  
		 * transport.connect(MailConstants.SMTP_HOST_OF_SINA, emailSender, PasswordUtils.readPassword(emailSender));  
		 * // 将message对象传递给transport对象, 将邮件发送出去  
		 * transport.sendMessage(message, message.getAllRecipients());  
		 * // 关闭连接
		 * transport.close();
		 * 
		 * // 此方法内部调用了上述方法
		 * Transport.send(message);
		 * </code>
		 */
	}
}
